Get Historical Rate
Query historical exchange rates by date for a foreign currency against VND. Each date returns the closing rate (end-of-day rate) for both SELL and BUY directions, supporting reconciliation and analysis.
Workflow
Endpoint
- URL:
/api/v1/fx/historical-rate - Method:
POST
Request
| Parameter | Data Type | Required | Description |
|---|---|---|---|
| request_id | string(50) | Yes | See section 3 Introduction |
| request_time | string(19) | Yes | See section 3 Introduction |
| merchant_code | string(20) | Yes | See section 3 Introduction |
| currency | string(3) | Yes | Foreign currency to query (paired against VND), e.g., USD |
| from_date | string(10) | Yes | Query start date (inclusive), format YYYY-MM-DD |
| to_date | string(10) | Yes | Query end date (inclusive), format YYYY-MM-DD. Constraint: to_date ≥ from_date, query span max 30 days, to_date not greater than today. |
Example Request
{
"request_id": "MERCHANT1234BK202606050004",
"request_time": "2026-06-05 10:16:30",
"merchant_code": "MERCHANT1234",
"currency": "USD",
"from_date": "2026-06-01",
"to_date": "2026-06-04"
}
Response
| Parameter | Data Type | Required | Description |
|---|---|---|---|
| response_code | int(4) | Yes | Result code |
| response_message | string(200) | Yes | Result code description |
| merchant_code | string(20) | Yes | Merchant code |
| currency_pair | string(10) | Yes | Standardized currency pair, e.g., USD/VND |
| data | Array of Objects | Yes | List of rates by date, sorted ascending. Dates without data do not appear. |
Data Array Structure
| Parameter | Data Type | Description |
|---|---|---|
| date | string(10) | Date of the rate, format YYYY-MM-DD |
| sell_rate | decimal(18,4) | End-of-day closing rate for SELL direction (Merchant sells foreign currency, receives VND) |
| buy_rate | decimal(18,4) | End-of-day closing rate for BUY direction (Merchant uses VND to buy foreign currency) |
Example Response
{
"response_code": 200,
"response_message": "Success",
"merchant_code": "MERCHANT1234",
"currency_pair": "USD/VND",
"data": [
{ "date": "2026-06-01", "sell_rate": 26430.0000, "buy_rate": 26495.0000 },
{ "date": "2026-06-02", "sell_rate": 26440.0000, "buy_rate": 26500.0000 },
{ "date": "2026-06-03", "sell_rate": 26445.0000, "buy_rate": 26505.0000 },
{ "date": "2026-06-04", "sell_rate": 26450.0000, "buy_rate": 26510.0000 }
]
}
Error Codes
| Response Code | Response Message | Description |
|---|---|---|
| 200 | Success | |
| 101 | System Error | Unexpected error on Baokim's side |
| 110 | Invalid Merchant Code | merchant_code is undefined |
| 120 | Invalid Signature | Header Signature is invalid |
| 404 | Currency Not Supported | Requested foreign currency is not in Merchant's configuration |
| 416 | Invalid Date Range | to_date < from_date, span > 30 days, or to_date > today |
| 422 | Validation Error | Request field is missing or invalid |
| 429 | Too Many Requests | Exceeded rate limit for Merchant |